Package com.cisco.pt.ipc
package com.cisco.pt.ipc
Java Framework built for Packet Tracer 8.1.0. This framework is an API that connects
to Packet Tracer using TCP and communicates using the Packet Tracer Messaging Protocol (PTMP).
The default Packet Tracer IPC port is 39000. To use this framework, take a look at the example below.
import java.io.IOException;
import com.cisco.pt.impl.*; // import basic PTMP types
import com.cisco.pt.ptmp.PacketTracerSession; // The session with PT
import com.cisco.pt.ptmp.PacketTracerSessionFactory; // The session factory
import com.cisco.pt.ptmp.impl.*; // import PTMP connection classes
import com.cisco.pt.impl.OptionsManager; // Class to read connection options from file
import com.cisco.pt.ptmp.ConnectionNegotiationProperties; // Class that PTMP will use to negotiate connection parameters
import com.cisco.pt.ipc.IPCFactory; // Class that creates PT objects
import com.cisco.pt.ipc.enums.*; // package containing all enums in PT.
import com.cisco.pt.ipc.ui.*; // package containing all UI elements from PT
import com.cisco.pt.ipc.sim.*; // package containing simulation elements from PT
import com.cisco.pt.ipc.events.*; // package containing events from PT
import com.cisco.pt.ipc.sim.pdu.impl.*; // package containing PDU specifications from PT
import com.cisco.pt.ipc.system.NetworkFile; // The class represents a single PT file, activity files can be casted to ActivtyFile
import com.cisco.pt.ipc.system.Options; // PT options
import java.util.ArrayList;
public class JavaFwTest {
public JavaFwTest(PacketTracerSession session) {
}
public static void main(String[] args) {
try {
// Start by getting an instance of the PT Session factory
PacketTracerSessionFactory packetTracerSessionFactory = PacketTracerSessionFactoryImpl.getInstance();
// Get the options used to connect to PT
ConnectionNegotiationProperties cnp = OptionsManager.getInstance().getConnectOpts();
// Modify the default options to specify your application parameters
cnp.setAuthenticationSecret("cisco");
cnp.setAuthenticationApplication("net.netacad.cisco.javafwtest");
// Create a PT session
PacketTracerSession packetTracerSession = packetTracerSessionFactory.openSession("localhost", 39000, cnp);
// Get the top level IPC object to communicate with PT
IPCFactory ipcFactory = new IPCFactory(packetTracerSession);
final IPC ipc = ipcFactory.getIPC();
// Get the object representing PT's network
Network network = ipc.network();
// Get the object representing PT's GUI window
AppWindow appWindow = ipc.appWindow();
// Get the object representing PT's current file
NetworkFile file = appWindow.getActiveFile();
// Get the current PT options
Options options = file.getOptions();
// Change an option
options.setBufferFullAction(BufferFullAction.AUTO_CLEAR_EVENT_LIST);
// Get the event manager that contains all of the top level event registries
IPCEventManager ipcEventManager = packetTracerSession.getEventManager();
// Get the event registry for the simulation panel
SimulationEventRegistry simRegistry = ipcEventManager.getSimulationEvents();
// To listen to events, you can listen to all events of an object, or just single events from an object.
// To listen for specific events, create an ArrayList<String> and push in specific events to listen for.
// All events have a constant specified in the IPCEventConstants class. Use those constants for specific events.
List<String> simCallbackList = new ArrayList<String>();
simCallbackList.add(IPCEventConstants.SIMULATION_NEW_FRAME_INSTANCE_ADDED);
// Create a new listener class that overrides the event listener you want to listen events for.
// Here we are overriding the SimulationEventListener and override the handleEvent function.
// All event listener classes use the handleEvent function.
simRegistry.addSpecificListenerFiltered(
new SimulationEventListener() {
\@Override
public void handleEvent(SimulationEvent evt) {
// Find out what specific simulation event it is
switch (evt.type) {
case NEW_FRAME_INSTANCE_ADDED:
// Cast the event to the specific simulation event type
SimulationEvent.NewFrameInstanceAdded simevent = (SimulationEvent.NewFrameInstanceAdded) evt;
// Do something with this event. Here we are going to get a FrameInstance from that frame, which contains
// information about the PDU.
FrameInstance frame = ipc.simulation().getFrameInstanceAt(simevent.index);
}
}
}, ipc.simulation(), simCallbackList);
// For the addSpecificListenerFiltered, put in the object and event list to listen for.
// Use null to listen for all events.
} catch (Exception e) {
e.printStackTrace();
}
// Get the Realtime-Simulation Switch GUI object and change to Simulation Mode.
appWindow.getRSSwitch().showSimulationMode();
}
}
The above example simply starts a connection to Packet Tracer and listen for new frames from the simulation
event panel. Then it switches to simulation mode. If there are no packets in the network, the event will not
be generated. Use the objects available to do something more meaningful.
<p>
Some data are derived from IPCObject and some data are derived from IPCData objects. IPCObject classes are cached calls to PT. What
this means is that if you cache an IPCObject, for example Device router = network().getDevice("Router0");,
router is a cached call to PT the refers to "network().getDevice("Router0");". It does not refer to the
"Router0" in PT. If after the first call Device router = network().getDevice("Router0");, and you did
router.setName("R0"); , router still refers to "network().getDevice("Router0");", and so
if you were to use router.getName(); it will not work. On the other hand, if your initial code was
Device router = network().getDeviceAt(0); , then the call will be different, and calling setName()
will not invalidate router . In this case, if you were to remove the first device, then there will be
a new (if any) first device, and subsequent calls to router will refer to the wrong device.
<p>
IPCData objects are not cached calls, rather they contain entire objects from PT with the data filled in
and an equivalent java class instance is created to contain this data. Calls to this data class do not result
in another call to PT. Changes to the data structure in PT are not automatically propagated back to this object.
It is in essence a snapshot copy of the data from PT at the moment of the call.
<p>
Specify your own application parameters, such as the name, secret key, and other parameters.
You may do so using code, or by using your own pt.cep.properties
file located in your application dir. Example of the pt.cep.properties file is as follows:
# Properties file for Packet Tracer Java CEP
# set PTMP parameters
pt.cep.ptmp.uid={c6fbf435-3234-48bb-af04-debc4e4cf9f3}
pt.cep.ptmp.signature=PTMP
pt.cep.ptmp.version=1
# set connection parameters
# set encoding to TEXT_ENCODING or BINARY_ENCODING
pt.cep.encoding=TEXT_ENCODING
# set encryption to NO_ENCRYPTION or XOR_ENCRYPTION
pt.cep.encryption=NO_ENCRYPTION
# set compression to NOT_COMPRESSED or ZLIB_COMPRESSED
pt.cep.compression=NOT_COMPRESSED
# set authentication to SIMPLE_AUTH, CLEAR_TEXT_AUTH or MD5_AUTH (currently only MD5_AUTH is supported)
pt.cep.authentication=MD5_AUTH
# set authentication parameters
pt.cep.auth.secret=password
pt.cep.auth.application=company.group.appname
Before you connect to PT, you must configure PT to allow your application. By default, PT locates
the available applications in %installation dir%\extensions and %homedir%\%installation dir%\extensions.
For Windows, this usually means
C:\Program Files\Cisco Packet Tracer\extensionsand
C:\Users\your username\Cisco Packet Tracer\extensions.<p> Place your application into one of those directories. Your application must contain a <appname>.pta file which specifies the application security details. This .pta file is an encrypted XML file. The XML file is in this format:
<?xml version="1.0" encoding = "iso-8859-1"?>
<!DOCTYPE PT_APP_META>
<PT_APP_META>
<PT_VERSION>7.0.0</PT_VERSION>
<IPC_VERSION>1.2</IPC_VERSION>
<NAME>appname</NAME>
<VERSION>1.2</VERSION>
<ID>company.group.appname</ID>
<DESCRIPTION>Description</DESCRIPTION>
<AUTHOR>Name</AUTHOR>
<CONTACT>email</CONTACT>
<EXECUTABLE_PATH>appname.class</EXECUTABLE_PATH>
<KEY>password</KEY>
<SECURITY_SETTINGS>
<PRIVILEGE>GET_NETWORK_INFO</PRIVILEGE>
<PRIVILEGE>CHANGE_NETWORK_INFO</PRIVILEGE>
<PRIVILEGE>SIMULATION_MODE</PRIVILEGE>
<PRIVILEGE>MISC_GUI</PRIVILEGE>
<PRIVILEGE>FILE</PRIVILEGE>
<PRIVILEGE>CHANGE_PREFERENCES</PRIVILEGE>
<PRIVILEGE>CHANGE_GUI</PRIVILEGE>
<PRIVILEGE>ACTIVITY_WIZARD</PRIVILEGE>
<PRIVILEGE>MULTIUSER</PRIVILEGE>
<PRIVILEGE>IPC</PRIVILEGE>
<PRIVILEGE>APPLICATION</PRIVILEGE>
</SECURITY_SETTINGS>
<LOADING>ON_STARTUP</LOADING>
<SAVING>NEVER</SAVING>
<INSTANCES>1</INSTANCES>
</PT_APP_META>
Replace the above values with your application's values. Remove unnecessary privileges. After this xml is
created, encrypt it using the executable "meta" located in the %installation dir%\extensions folder.
eg:meta appname.pta appname.xml appname_executableYou may not have the Qt libraries installed system wide to run the meta application. In Linux, you may set the LD_LIBRARY_PATH to %installation dir%/lib before running it. In Windows, you can launch it from within the %installation dir%\bin folder. <br>
eg: C:\Program Files\Cisco Packet Tracer\bin>..\extensions\meta ..\extensions\appname\appname.pta ..\extensions\appname\appname.xml ..\extensions\appname\appname.jar.
</br>
Once created, you should not include your xml file with your application for distribution. Doing so would
allow others to pose as your application using your application credentials. While PT will detect changes
to the executable, it is easy for another person to generate the credentials with their own executable instead.
<p>
Upon launching Packet Tracer, it should detect the new application and prompts you to authorize it. If
the application is set to launch on demand, you must manually launch it. You may manually launch it like you
would launch any normal application, or you may launch it from Packet Tracer.
<p>
It is also possible to launch Packet Tracer from your application by using the classes in the com.cisco.pt.launcher package.
Launching Packet Tracer from your application allows you to set launch parameters for PT, such as hiding the GUI
and changing the ipc port.- Version:
- 7.0.0
- Author:
- Tony Deng
-
ClassDescriptionA simple class to hold constants used in various IPC calls